package com.kexio.user.service;

import java.util.List;
import java.util.Map;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.kexio.user.entity.Permission;
import com.kexio.user.entity.Role;
import com.kexio.user.entity.User;

/**
 * 权限服务接口
 * 
 * 提供权限管理的核心业务逻辑，包括：
 * - 权限CRUD操作
 * - 权限树形结构管理
 * - 权限关联查询
 * - 权限继承处理
 * - 多租户数据隔离
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface PermissionService {
    
    // ==================== 基础CRUD操作 ====================
    
    /**
     * 创建权限
     * 
     * @param permission 权限信息
     * @return 创建的权限信息
     */
    Permission createPermission(Permission permission);
    
    /**
     * 根据ID更新权限信息
     * 
     * @param permissionId 权限ID
     * @param permission 更新的权限信息
     * @return 更新后的权限信息
     */
    Permission updatePermission(String permissionId, Permission permission);
    
    /**
     * 根据ID删除权限（逻辑删除）
     * 
     * @param permissionId 权限ID
     * @return 是否删除成功
     */
    boolean deletePermission(String permissionId);
    
    /**
     * 根据ID查询权限信息
     * 
     * @param permissionId 权限ID
     * @return 权限信息
     */
    Permission getPermissionById(String permissionId);
    
    /**
     * 根据权限编码查询权限信息
     * 
     * @param permissionCode 权限编码
     * @return 权限信息
     */
    Permission getPermissionByCode(String permissionCode);
    
    // ==================== 权限列表查询 ====================
    
    /**
     * 分页查询权限列表
     * 
     * @param current 当前页码
     * @param size 每页大小
     * @return 分页权限列表
     */
    Page<Permission> getPermissionPage(Long current, Long size);
    
    /**
     * 带条件分页查询权限列表
     * 
     * @param current 当前页码
     * @param size 每页大小
     * @param permissionCode 权限编码（可选）
     * @param permissionName 权限名称（可选）
     * @param permissionType 权限类型（可选）
     * @param status 状态（可选）
     * @param menuId 菜单ID（可选）
     * @return 分页权限列表
     */
    Page<Permission> getPermissionPage(Long current, Long size,
                                       String permissionCode, String permissionName, 
                                       String permissionType, Integer status, String menuId);
    
    /**
     * 查询租户下的所有权限
     * 
     * @return 权限列表
     */
    List<Permission> getPermissionsByTenant();
    
    /**
     * 根据权限类型查询权限列表
     * 
     * @param permissionType 权限类型
     * @return 权限列表
     */
    List<Permission> getPermissionsByType(String permissionType);
    
    /**
     * 查询启用状态的权限列表
     * 
     * @return 启用权限列表
     */
    List<Permission> getActivePermissions();
    
    // ==================== 权限树形结构 ====================
    
    /**
     * 查询权限树结构
     * 
     * @return 权限树列表（需要在Service层构建父子关系）
     */
    List<Permission> getPermissionTree();
    
    /**
     * 根据菜单ID查询权限列表
     * 
     * @param menuId 菜单ID
     * @return 权限列表
     */
    List<Permission> getPermissionsByMenuId(String menuId);
    
    /**
     * 获取所有菜单的权限映射（用于前端按菜单分组显示）
     * 
     * @return 菜单ID -> 权限列表的映射
     */
    Map<String, List<Permission>> getMenuPermissionMap();
    
    
    
    
    // ==================== 权限检查 ====================
    
    /**
     * 检查用户是否拥有指定权限
     * 
     * @param userId 用户ID
     * @param permissionCode 权限编码
     * @return 是否拥有权限
     */
    boolean hasPermission(String userId, String permissionCode);
    
    /**
     * 检查用户是否拥有任一权限
     * 
     * @param userId 用户ID
     * @param permissionCodes 权限编码列表
     * @return 是否拥有任一权限
     */
    boolean hasAnyPermission(String userId, List<String> permissionCodes);
    
    /**
     * 检查用户是否拥有所有权限
     * 
     * @param userId 用户ID
     * @param permissionCodes 权限编码列表
     * @return 是否拥有所有权限
     */
    boolean hasAllPermissions(String userId, List<String> permissionCodes);
    
    /**
     * 检查角色是否拥有指定权限
     * 
     * @param roleId 角色ID
     * @param permissionCode 权限编码
     * @return 是否拥有权限
     */
    boolean roleHasPermission(String roleId, String permissionCode);
    
    // ==================== 权限继承处理 ====================
    
    /**
     * 获取权限的有效权限列表（包含继承的权限）
     * 
     * @param permissionId 权限ID
     * @return 有效权限列表
     */
    List<Permission> getEffectivePermissions(String permissionId);
    
    /**
     * 检查权限是否继承自父权限
     * 
     * @param childPermissionId 子权限ID
     * @param parentPermissionId 父权限ID
     * @return 是否继承
     */
    boolean isPermissionInherited(String childPermissionId, String parentPermissionId);
    
    // ==================== 统计查询 ====================
    
    /**
     * 统计租户权限总数
     * 
     * @return 权限总数
     */
    Long countPermissionsByTenant();
    
    /**
     * 统计启用的权限数量
     * 
     * @return 启用权限数
     */
    Long countActivePermissions();
    
    /**
     * 统计各类型权限数量
     * 
     * @return 类型统计结果 Map<权限类型, 数量>
     */
    java.util.Map<String, Long> countPermissionsByType();
    
    /**
     * 统计权限分配给的角色数量
     * 
     * @param permissionId 权限ID
     * @return 角色数量
     */
    Long countPermissionRoles(String permissionId);
    
    // ==================== 数据验证 ====================
    
    /**
     * 检查权限编码是否存在
     * 
     * @param permissionCode 权限编码
     * @param excludePermissionId 排除的权限ID（用于更新时检查）
     * @return 是否存在
     */
    boolean existsByCode(String permissionCode, String excludePermissionId);
    
    /**
     * 检查权限名称是否存在
     * 
     * @param permissionName 权限名称
     * @param excludePermissionId 排除的权限ID（用于更新时检查）
     * @return 是否存在
     */
    boolean existsByName(String permissionName, String excludePermissionId);
    
    /**
     * 检查权限是否被使用（是否有角色分配）
     * 
     * @param permissionId 权限ID
     * @return 是否被使用
     */
    boolean isPermissionInUse(String permissionId);
    
    /**
     * 检查资源路径是否唯一
     * 
     * @param resourcePath 资源路径
     * @param excludePermissionId 排除的权限ID（用于更新时检查）
     * @return 是否唯一
     */
    boolean isResourcePathUnique(String resourcePath, String excludePermissionId);
    
    // ==================== 缓存管理 ====================
    
    /**
     * 刷新权限缓存
     * 
     */
    void refreshPermissionCache();
    
    /**
     * 刷新用户权限缓存
     * 
     * @param userId 用户ID
     */
    void refreshUserPermissionCache(String userId);
    
    /**
     * 权限变更通知
     * 
     * 在权限发生变更时调用，用于：
     * - 增加权限版本号
     * - 清除相关缓存
     * - 发送变更通知
     * 
     * @param permissionId 权限ID
     * @param operatorId 操作者ID
     */
    void notifyPermissionChange(String permissionId, String operatorId);
    
    // ==================== 权限状态管理 ====================
    
    /**
     * 更新权限状态
     * 
     * @param permissionId 权限ID
     * @param status 状态：1-启用，0-禁用
     * @return 是否更新成功
     */
    boolean updatePermissionStatus(String permissionId, Integer status);
    
    // ==================== 权限关联查询 ====================
    
    /**
     * 查询权限关联的角色列表
     * 
     * @param permissionId 权限ID
     * @return 角色列表
     */
    List<Role> getPermissionRoles(String permissionId);
    
    /**
     * 查询权限关联的用户列表（根据权限ID）
     * 
     * @param permissionId 权限ID
     * @return 用户列表
     */
    List<User> getPermissionUsers(String permissionId);
    
    /**
     * 根据模式统计权限数量
     * 
     * @param pattern 权限模式（如："system:user:*"）
     * @return 匹配的权限数量
     */
    Long countPermissionsByPattern(String pattern);
}
